Návrh schématu GraphQL: Škálovatelné vzory pro globální API

GraphQL se stal silnou alternativou k tradičním REST API a nabízí klientům flexibilitu vyžádat si přesně ta data, která potřebují. S rostoucí složitostí a rozsahem vašeho GraphQL API – zejména pokud slouží globálnímu publiku s různými datovými požadavky – se však pečlivý návrh schématu stává klíčovým pro udržovatelnost, škálovatelnost a výkon. Tento článek zkoumá několik škálovatelných návrhových vzorů pro schémata GraphQL, které vám pomohou vytvořit robustní API schopná zvládnout požadavky globální aplikace.

Důležitost škálovatelného návrhu schématu

Dobře navržené schéma GraphQL je základem úspěšného API. Určuje, jak mohou klienti interagovat s vašimi daty a službami. Špatný návrh schématu může vést k řadě problémů, včetně:

• Úzká místa ve výkonu: Neefektivní dotazy a resolvery mohou přetížit vaše datové zdroje a zpomalit doby odezvy.
• Problémy s udržovatelností: Monolitické schéma se stává obtížně pochopitelným, upravitelným a testovatelným s růstem vaší aplikace.
• Bezpečnostní zranitelnosti: Špatně definovaná kontrola přístupu může odhalit citlivá data neoprávněným uživatelům.
• Omezená škálovatelnost: Pevně svázané schéma ztěžuje distribuci vašeho API na více serverů nebo týmů.

U globálních aplikací jsou tyto problémy ještě výraznější. Různé regiony mohou mít odlišné datové požadavky, regulační omezení a očekávání ohledně výkonu. Škálovatelný návrh schématu vám umožní tyto výzvy efektivně řešit.

Klíčové principy škálovatelného návrhu schématu

Než se ponoříme do konkrétních vzorů, nastíníme si několik klíčových principů, kterými by se měl váš návrh schématu řídit:

• Modularita: Rozdělte své schéma na menší, nezávislé moduly. To usnadňuje pochopení, úpravy a opětovné použití jednotlivých částí vašeho API.
• Skládání (Composability): Navrhněte své schéma tak, aby bylo možné různé moduly snadno kombinovat a rozšiřovat. To vám umožní přidávat nové funkce bez narušení stávajících klientů.
• Abstrakce: Skryjte složitost vašich podkladových datových zdrojů a služeb za dobře definované rozhraní GraphQL. To vám umožní měnit implementaci bez dopadu na klienty.
• Konzistence: Udržujte konzistentní konvenci pojmenování, datovou strukturu a strategii pro zpracování chyb v celém schématu. To klientům usnadní učení a používání vašeho API.
• Optimalizace výkonu: Zvažujte dopady na výkon v každé fázi návrhu schématu. Používejte techniky jako data loadery a aliasing polí k minimalizaci počtu databázových dotazů a síťových požadavků.

Škálovatelné návrhové vzory pro schémata

Zde je několik škálovatelných návrhových vzorů, které můžete použít k vytvoření robustních GraphQL API:

1. Schema Stitching (Spojování schémat)

Schema stitching umožňuje zkombinovat více GraphQL API do jednoho, sjednoceného schématu. To je zvláště užitečné, když máte různé týmy nebo služby zodpovědné za různé části vašich dat. Je to jako mít několik mini-API a spojit je dohromady prostřednictvím 'gateway' API.

Jak to funguje:

1. Každý tým nebo služba vystavuje své vlastní GraphQL API s vlastním schématem.
2. Centrální gateway služba používá nástroje pro schema stitching (jako Apollo Federation nebo GraphQL Mesh) k sloučení těchto schémat do jednoho, sjednoceného schématu.
3. Klienti komunikují s gateway službou, která směruje požadavky na příslušná podkladová API.

Příklad:

Představte si e-commerce platformu se samostatnými API pro produkty, uživatele a objednávky. Každé API má své vlastní schéma:

  
    # Products API
    type Product {
      id: ID!
      name: String!
      price: Float!
    }

    type Query {
      product(id: ID!): Product
    }

    # Users API
    type User {
      id: ID!
      name: String!
      email: String!
    }

    type Query {
      user(id: ID!): User
    }

    # Orders API
    type Order {
      id: ID!
      userId: ID!
      productId: ID!
      quantity: Int!
    }

    type Query {
      order(id: ID!): Order
    }
  

Gateway služba může tato schémata spojit a vytvořit tak sjednocené schéma:

  
    type Product {
      id: ID!
      name: String!
      price: Float!
    }

    type User {
      id: ID!
      name: String!
      email: String!
    }

    type Order {
      id: ID!
      user: User! @relation(field: "userId")
      product: Product! @relation(field: "productId")
      quantity: Int!
    }

    type Query {
      product(id: ID!): Product
      user(id: ID!): User
      order(id: ID!): Order
    }
  

Všimněte si, jak typ Order nyní obsahuje reference na User a Product, přestože jsou tyto typy definovány v samostatných API. Toho je dosaženo pomocí direktiv pro schema stitching (jako @relation v tomto příkladu).

Výhody:

• Decentralizované vlastnictví: Každý tým může spravovat svá vlastní data a API nezávisle.
• Zlepšená škálovatelnost: Každé API můžete škálovat nezávisle podle jeho specifických potřeb.
• Snížená složitost: Klienti potřebují komunikovat pouze s jedním API endpointem.

Zvažte:

• Složitost: Schema stitching může přidat složitost do vaší architektury.
• Latence: Směrování požadavků přes gateway službu může způsobit latenci.
• Zpracování chyb: Musíte implementovat robustní zpracování chyb pro řešení selhání v podkladových API.

2. Schema Federation (Federace schémat)

Federace schémat je evolucí spojování schémat (schema stitching), navržená tak, aby řešila některé jeho nedostatky. Poskytuje deklarativnější a standardizovanější přístup ke skládání schémat GraphQL.

Jak to funguje:

1. Každá služba vystavuje GraphQL API a anotuje své schéma federačními direktivami (např. @key, @extends, @external).
2. Centrální gateway služba (používající Apollo Federation) používá tyto direktivy k vytvoření supergrafu – reprezentace celého federovaného schématu.
3. Gateway služba používá supergraf ke směrování požadavků na příslušné podkladové služby a k řešení závislostí.

Příklad:

Při použití stejného příkladu z e-commerce by federovaná schémata mohla vypadat takto:

  
    # Products API
    type Product @key(fields: "id") {
      id: ID!
      name: String!
      price: Float!
    }

    type Query {
      product(id: ID!): Product
    }

    # Users API
    type User @key(fields: "id") {
      id: ID!
      name: String!
      email: String!
    }

    type Query {
      user(id: ID!): User
    }

    # Orders API
    type Order {
      id: ID!
      userId: ID!
      productId: ID!
      quantity: Int!
      user: User! @requires(fields: "userId")
      product: Product! @requires(fields: "productId")
    }

    extend type Query {
      order(id: ID!): Order
    }
  

Všimněte si použití federačních direktiv:

• @key: Specifikuje primární klíč pro daný typ.
• @requires: Označuje, že pole vyžaduje data z jiné služby.
• @extends: Umožňuje službě rozšířit typ definovaný v jiné službě.

Výhody:

• Deklarativní skládání: Federační direktivy usnadňují pochopení a správu závislostí schématu.
• Zlepšený výkon: Apollo Federation optimalizuje plánování a provádění dotazů pro minimalizaci latence.
• Vylepšená typová bezpečnost: Supergraf zajišťuje, že všechny typy jsou konzistentní napříč službami.

Zvažte:

• Nástroje: Vyžaduje použití Apollo Federation nebo kompatibilní implementace federace.
• Složitost: Nastavení může být složitější než u schema stitching.
• Křivka učení: Vývojáři se musí naučit federační direktivy a koncepty.

3. Modulární návrh schématu

Modulární návrh schématu zahrnuje rozdělení velkého, monolitického schématu na menší, lépe spravovatelné moduly. To usnadňuje pochopení, úpravy a opětovné použití jednotlivých částí vašeho API, i bez použití federovaných schémat.

Jak to funguje:

Identifikujte logické hranice ve vašem schématu (např. uživatelé, produkty, objednávky).

Vytvořte samostatné moduly pro každou hranici, které definují typy, dotazy a mutace související s touto hranicí.

Použijte mechanismy importu/exportu (v závislosti na implementaci vašeho GraphQL serveru) ke spojení modulů do jednoho, sjednoceného schématu.

Příklad (s použitím JavaScript/Node.js):

Vytvořte samostatné soubory pro každý modul:

  
    // users.graphql
    type User {
      id: ID!
      name: String!
      email: String!
    }

    type Query {
      user(id: ID!): User
    }

    // products.graphql
    type Product {
      id: ID!
      name: String!
      price: Float!
    }

    type Query {
      product(id: ID!): Product
    }
  

Poté je zkombinujte ve svém hlavním souboru se schématem:

  
    // schema.js
    const { makeExecutableSchema } = require('graphql-tools');
    const { typeDefs: userTypeDefs, resolvers: userResolvers } = require('./users');
    const { typeDefs: productTypeDefs, resolvers: productResolvers } = require('./products');

    const typeDefs = [
      userTypeDefs,
      productTypeDefs,
      ""
    ];

    const resolvers = {
      Query: {
        ...userResolvers.Query,
        ...productResolvers.Query,
      }
    };

    const schema = makeExecutableSchema({
      typeDefs,
      resolvers,
    });

    module.exports = schema;
  

Výhody:

• Zlepšená udržovatelnost: Menší moduly jsou snáze pochopitelné a upravitelné.
• Zvýšená znovupoužitelnost: Moduly lze znovu použít v jiných částech vaší aplikace.
• Lepší spolupráce: Různé týmy mohou pracovat na různých modulech nezávisle.

Zvažte:

• Režie: Modularizace může do vašeho vývojového procesu přidat určitou režii.
• Složitost: Musíte pečlivě definovat hranice mezi moduly, abyste se vyhnuli cyklickým závislostem.
• Nástroje: Vyžaduje použití implementace GraphQL serveru, která podporuje modulární definici schématu.

4. Typy Interface a Union

Typy Interface a Union vám umožňují definovat abstraktní typy, které mohou být implementovány více konkrétními typy. To je užitečné pro reprezentaci polymorfních dat – dat, která mohou nabývat různých forem v závislosti na kontextu.

Jak to funguje:

• Definujte typ interface nebo union se sadou společných polí.
• Definujte konkrétní typy, které implementují interface nebo jsou členy unionu.
• Použijte pole __typename k identifikaci konkrétního typu za běhu.

Příklad:

  
    interface Node {
      id: ID!
    }

    type User implements Node {
      id: ID!
      name: String!
      email: String!
    }

    type Product implements Node {
      id: ID!
      name: String!
      price: Float!
    }

    union SearchResult = User | Product

    type Query {
      node(id: ID!): Node
      search(query: String!): [SearchResult!]!
    }
  

V tomto příkladu User i Product implementují rozhraní Node, které definuje společné pole id. Union typ SearchResult představuje výsledek vyhledávání, který může být buď User, nebo Product. Klienti se mohou dotazovat na pole `search` a poté pomocí pole `__typename` určit, jaký typ výsledku obdrželi.

Výhody:

• Flexibilita: Umožňuje reprezentovat polymorfní data typově bezpečným způsobem.
• Opakované použití kódu: Snižuje duplicitu kódu definováním společných polí v rozhraních a unionech.
• Zlepšená dotazovatelnost: Usnadňuje klientům dotazování na různé typy dat pomocí jediného dotazu.

Zvažte:

• Složitost: Může přidat složitost do vašeho schématu.
• Výkon: Rozlišování typů interface a union může být nákladnější než rozlišování konkrétních typů.
• Introspekce: Vyžaduje, aby klienti používali introspekci k určení konkrétního typu za běhu.

5. Vzor Connection (pro stránkování)

Vzor Connection je standardní způsob implementace stránkování v GraphQL API. Poskytuje konzistentní a efektivní způsob, jak načítat velké seznamy dat po částech.

Jak to funguje:

• Definujte typ connection s poli edges a pageInfo.
• Pole edges obsahuje seznam hran (edges), z nichž každá obsahuje pole node (skutečná data) a pole cursor (jedinečný identifikátor uzlu).
• Pole pageInfo obsahuje informace o aktuální stránce, například zda existují další stránky a kurzory pro první a poslední uzly.
• K ovládání stránkování použijte argumenty first, after, last a before.

Příklad:

  
    type User {
      id: ID!
      name: String!
      email: String!
    }

    type UserEdge {
      node: User!
      cursor: String!
    }

    type UserConnection {
      edges: [UserEdge!]!
      pageInfo: PageInfo!
    }

    type PageInfo {
      hasNextPage: Boolean!
      hasPreviousPage: Boolean!
      startCursor: String
      endCursor: String
    }

    type Query {
      users(first: Int, after: String, last: Int, before: String): UserConnection!
    }
  

Výhody:

• Standardizované stránkování: Poskytuje konzistentní způsob implementace stránkování napříč vaším API.
• Efektivní načítání dat: Umožňuje načítat velké seznamy dat po částech, což snižuje zátěž na váš server a zlepšuje výkon.
• Stránkování založené na kurzorech: Používá kurzory ke sledování pozice každého uzlu, což je efektivnější než stránkování založené na offsetu.

Zvažte:

• Složitost: Může přidat složitost do vašeho schématu.
• Režie: Vyžaduje další pole a typy pro implementaci vzoru connection.
• Implementace: Vyžaduje pečlivou implementaci, aby bylo zajištěno, že kurzory jsou jedinečné a konzistentní.

Globální aspekty

Při návrhu schématu GraphQL pro globální publikum zvažte tyto další faktory:

• Lokalizace: Používejte direktivy nebo vlastní skalární typy pro podporu různých jazyků a regionů. Můžete mít například vlastní skalár `LocalizedText`, který ukládá překlady pro různé jazyky.
• Časová pásma: Ukládejte časová razítka v UTC a umožněte klientům specifikovat jejich časové pásmo pro účely zobrazení.
• Měny: Používejte konzistentní formát měny a umožněte klientům specifikovat preferovanou měnu pro účely zobrazení. Zvažte vlastní skalár `Currency` pro reprezentaci tohoto.
• Rezidence dat: Zajistěte, aby vaše data byla ukládána v souladu s místními předpisy. To může vyžadovat nasazení vašeho API do více regionů nebo použití technik maskování dat.
• Přístupnost: Navrhněte své schéma tak, aby bylo přístupné uživatelům se zdravotním postižením. Používejte jasné a popisné názvy polí a poskytněte alternativní způsoby přístupu k datům.

Zvažte například pole pro popis produktu:

type Product {
 id: ID!
 name: String!
 description(language: String = "en"): String!
}

To umožňuje klientům vyžádat si popis v konkrétním jazyce. Pokud není jazyk specifikován, použije se výchozí angličtina (`en`).

Závěr

Škálovatelný návrh schématu je nezbytný pro vytváření robustních a udržovatelných GraphQL API, která zvládnou požadavky globální aplikace. Dodržováním principů uvedených v tomto článku a používáním vhodných návrhových vzorů můžete vytvářet API, která jsou snadno pochopitelná, upravitelná a rozšiřitelná a zároveň poskytují vynikající výkon a škálovatelnost. Nezapomeňte své schéma modularizovat, skládat a abstrahovat a zohlednit specifické potřeby vašeho globálního publika.

Přijetím těchto vzorů můžete odemknout plný potenciál GraphQL a vytvářet API, která budou pohánět vaše aplikace po mnoho let.